Inside Macintosh: Sound
| Previous | Chapter contents | Chapter top | Section top | Next |
Use the SndStartFilePlay , SndPauseFilePlay , and SndStopFilePlay functions to manage a continuous play from disk.
You can call the SndStartFilePlay function to initiate a play from disk.
FUNCTION SndStartFilePlay (chan: SndChannelPtr; fRefNum: Integer;
resNum: Integer; bufferSize: LongInt;
theBuffer: Ptr;
theSelection: AudioSelectionPtr;
theCompletion: ProcPtr;
async: Boolean): OSErr;
The SndStartFilePlay function begins a continuous play from disk on a sound channel. The chan parameter is a pointer to the sound channel. If chan is not NIL , it is used as a valid channel. If chan is NIL , an internally allocated sound channel is used for play from disk. This internally allocated sound channel is not passed back to you. Because SndPauseFilePlay and SndStopFilePlay require a sound-channel pointer, you must allocate your own channel if you wish to use those routines.
The sounds you wish to play can be stored either in a file or in an 'snd ' resource. If you are playing a file, then fRefNum should be the file reference number of the file to be played and the parameter resNum should be set to 0. If you are playing an 'snd ' resource, then fRefNum should be set to 0 and resNum should be the resource ID number (not the file reference number) of the resource to play.
The SndStartFilePlay function might not play 'snd ' resources from disk correctly. In particular, the function will not execute correctly if any resource in the resource file containing the 'snd ' resource you wish to play has been changed through a call to the WriteResource procedure and you have not updated the resource file using the UpdateResFile procedure. To avoid this and other problems, you should use the SndStartFilePlay function to play only sound files.
Because the SndStartFilePlay function moves memory, you should not call it at interrupt time.
The trap macro and routine selector for the SndStartFilePlay function are
For an example of how to play a sound file, see the chapter "Introduction to Sound on the Macintosh" in this book.
For information on the format of a completion routine, see "Completion Routines" .
You can use the SndPauseFilePlay function to toggle the state of a play from disk in progress, just as you might use the pause button on an audiocassette tape player to temporarily pause and then resume play.
FUNCTION SndPauseFilePlay (chan: SndChannelPtr): OSErr;
The SndPauseFilePlay function suspends the play from disk on the channel specified by the chan parameter if that play from disk is not already paused; the function resumes play if the play from disk is already paused.
The SndPauseFilePlay function is used in conjunction with SndStopFilePlay to control play from disk on a sound channel. Note that this call can be made only if your application has already called SndStartFilePlay with a valid sound channel. You cannot use this function with a synchronous call to SndStartFilePlay because, in that case, program control does not return to the caller until after the sound has completely finished playing.
If the channel specified by the chan parameter is not being used for play from disk, then SndPauseFilePlay returns the result code channelNotBusy . If the channel is busy and paused, then play from disk is resumed. If the channel is busy and the channel is not paused, then play from disk is suspended.
You can use SndStopFilePlay to stop an asynchronous play from disk.
FUNCTION SndStopFilePlay (chan: SndChannelPtr;
quietNow: Boolean): OSErr;
The SndStopFilePlay function either can stop an asynchronous play from disk immediately or can take control of the CPU until a play from disk finishes. The SndStopFilePlay function does not return until all asynchronous file I/O calls have completed and any internally allocated memory has been released. If async is FALSE , then SndStopFilePlay lets the sound complete normally and returns only after the sound has completed, all asynchronous file I/O calls have completed, and any internal allocated memory has been released.
For example, you might use the function to stop the playing of a sound file if the user selects an option that turns off sound output while the file is already playing. In that case, you would pass TRUE to quietNow . Alternatively, you might have started a sound playing asynchronously so that you could perform other tasks while the sound plays. But you might then finish those other tasks and want to convert the play from disk into a synchronous play. By passing FALSE to quietNow , you effectively achieve that.
Because the SndStopFilePlay function might move memory, you should not call it at interrupt time.
| Previous | Chapter contents | Chapter top | Section top | Next |